<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<title>Master test suite</title>
<link rel="stylesheet" href="../../../boostbook.css" type="text/css">
<meta name="generator" content="DocBook XSL Stylesheets V1.79.1">
<link rel="home" href="../../../index.html" title="Boost.Test">
<link rel="up" href="../test_tree.html" title="Test tree">
<link rel="prev" href="test_suite.html" title="Test suite">
<link rel="next" href="test_naming.html" title="Tests naming">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<table cellpadding="2" width="100%"><tr>
<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../../boost.png"></td>
<td align="center"><a href="../../../../../../../index.html">Home</a></td>
<td align="center"><a href="../../../../../../../libs/libraries.htm">Libraries</a></td>
<td align="center"><a href="http://www.boost.org/users/people.html">People</a></td>
<td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td>
<td align="center"><a href="../../../../../../../more/index.htm">More</a></td>
</tr></table>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="test_suite.html"><img src="../../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../test_tree.html"><img src="../../../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../../index.html"><img src="../../../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="test_naming.html"><img src="../../../../../../../doc/src/images/next.png" alt="Next"></a>
</div>
<div class="section">
<div class="titlepage"><div><div><h4 class="title">
<a name="boost_test.tests_organization.test_tree.master_test_suite"></a><a class="link" href="master_test_suite.html" title="Master test suite">Master
        test suite</a>
</h4></div></div></div>
<p>
          As defined in introduction section the master test suite is the <span class="bold"><strong>root</strong></span> node of the test tree. Each test module built
          with the <span class="emphasis"><em>Unit Test Framework</em></span> always has the (unique)
          master test suite defined. The <span class="emphasis"><em>Unit Test Framework</em></span>
          maintain the master test suite instance internally. All other test units
          are registered as direct or indirect children of the master test suite.
        </p>
<pre class="programlisting"><span class="keyword">namespace</span> <span class="identifier">boost</span> <span class="special">{</span>
<span class="keyword">namespace</span> <span class="identifier">unit_test</span> <span class="special">{</span>
<span class="keyword">class</span> <span class="identifier">master_test_suite_t</span> <span class="special">:</span> <span class="keyword">public</span> <span class="identifier">test_suite</span>
<span class="special">{</span>
  <span class="comment">/// implementation details</span>
<span class="keyword">public</span><span class="special">:</span>
  <span class="keyword">int</span> <span class="identifier">argc</span><span class="special">;</span>
  <span class="keyword">char</span><span class="special">**</span> <span class="identifier">argv</span><span class="special">;</span>
<span class="special">};</span>

<span class="special">}</span> <span class="comment">// namespace unit_test</span>
<span class="special">}</span> <span class="comment">// namespace boost</span>
</pre>
<p>
          To access single instance of the master test suite use the following interface:
        </p>
<pre class="programlisting"><span class="keyword">namespace</span> <span class="identifier">boost</span> <span class="special">{</span>
<span class="keyword">namespace</span> <span class="identifier">unit_test</span> <span class="special">{</span>
<span class="keyword">namespace</span> <span class="identifier">framework</span> <span class="special">{</span>

<span class="identifier">master_test_suite_t</span><span class="special">&amp;</span> <span class="identifier">master_test_suite</span><span class="special">();</span>

<span class="special">}</span> <span class="comment">// namespace framework</span>
<span class="special">}</span> <span class="comment">// namespace unit_test</span>
<span class="special">}</span> <span class="comment">// namespace boost</span>
</pre>
<h5>
<a name="boost_test.tests_organization.test_tree.master_test_suite.h0"></a>
          <span class="phrase"><a name="boost_test.tests_organization.test_tree.master_test_suite.command_line_arguments_access_in"></a></span><a class="link" href="master_test_suite.html#boost_test.tests_organization.test_tree.master_test_suite.command_line_arguments_access_in">Command
          line arguments access interface</a>
        </h5>
<p>
          Master test suite implemented as an extension to the regular test suite,
          since it maintains references to the command line arguments passed to the
          test module. To access the command line arguments use
        </p>
<pre class="programlisting"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">unit_test</span><span class="special">::</span><span class="identifier">framework</span><span class="special">::</span><span class="identifier">master_test_suite</span><span class="special">().</span><span class="identifier">argc</span>
<span class="identifier">boost</span><span class="special">::</span><span class="identifier">unit_test</span><span class="special">::</span><span class="identifier">framework</span><span class="special">::</span><span class="identifier">master_test_suite</span><span class="special">().</span><span class="identifier">argv</span>
</pre>
<p>
          In below example references to the command line arguments are accessible
          either as an initialization function parameters or as members of the master
          test suite. Both references point to the same values. A test module that
          uses the alternative initialization function specification can only access
          command line arguments through the master test suite.
        </p>
<p>
          Returning to the free function example, let's modify initialization function
          to check for absence of any test module arguments.
        </p>
<h6>
<a name="boost_test.tests_organization.test_tree.master_test_suite.h1"></a>
          <span class="phrase"><a name="boost_test.tests_organization.test_tree.master_test_suite.example_descr"></a></span><a class="link" href="master_test_suite.html#boost_test.tests_organization.test_tree.master_test_suite.example_descr">Example:
          Command line access in initialization function</a>
        </h6>
<div class="informaltable"><table class="table">
<colgroup><col></colgroup>
<thead><tr><th>
                  <p>
                    Code
                  </p>
                </th></tr></thead>
<tbody><tr><td>
<pre xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" class="table-programlisting"><span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">test</span><span class="special">/</span><span class="identifier">included</span><span class="special">/</span><span class="identifier">unit_test</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
<span class="keyword">using</span> <span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">unit_test</span><span class="special">;</span>

<span class="keyword">void</span> <span class="identifier">free_test_function</span><span class="special">()</span>
<span class="special">{</span>
  <span class="identifier">BOOST_TEST</span><span class="special">(</span> <span class="keyword">true</span> <span class="comment">/* test assertion */</span> <span class="special">);</span>
<span class="special">}</span>

<span class="identifier">test_suite</span><span class="special">*</span> <span class="identifier">init_unit_test_suite</span><span class="special">(</span> <span class="keyword">int</span> <span class="comment">/*argc*/</span><span class="special">,</span> <span class="keyword">char</span><span class="special">*</span> <span class="comment">/*argv*/</span><span class="special">[]</span> <span class="special">)</span>
<span class="special">{</span>
  <span class="keyword">if</span><span class="special">(</span> <span class="identifier">framework</span><span class="special">::</span><span class="identifier">master_test_suite</span><span class="special">().</span><span class="identifier">argc</span> <span class="special">&gt;</span> <span class="number">1</span> <span class="special">)</span>
    <span class="keyword">return</span> <span class="number">0</span><span class="special">;</span>

  <span class="identifier">framework</span><span class="special">::</span><span class="identifier">master_test_suite</span><span class="special">().</span>
    <span class="identifier">add</span><span class="special">(</span> <span class="identifier">BOOST_TEST_CASE</span><span class="special">(</span> <span class="special">&amp;</span><span class="identifier">free_test_function</span> <span class="special">)</span> <span class="special">);</span>

  <span class="keyword">return</span> <span class="number">0</span><span class="special">;</span>
<span class="special">}</span>
</pre>
                </td></tr></tbody>
</table></div>
<div class="informaltable"><table class="table">
<colgroup><col></colgroup>
<thead><tr><th>
                  <p>
                    Output
                  </p>
                </th></tr></thead>
<tbody><tr><td>
<pre xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" class="table-programlisting"><span class="special">&gt;</span> <span class="identifier">example</span> <span class="number">1</span>
<span class="identifier">Test</span> <span class="identifier">setup</span> <span class="identifier">error</span><span class="special">:</span> <span class="identifier">test</span> <span class="identifier">tree</span> <span class="identifier">is</span> <span class="identifier">empty</span>
</pre>
                </td></tr></tbody>
</table></div>
<a name="ref_BOOST_TEST_MODULE"></a><h5>
<a name="boost_test.tests_organization.test_tree.master_test_suite.h2"></a>
          <span class="phrase"><a name="boost_test.tests_organization.test_tree.master_test_suite.naming_the_master_test_suite"></a></span><a class="link" href="master_test_suite.html#boost_test.tests_organization.test_tree.master_test_suite.naming_the_master_test_suite">Naming
          the <span class="emphasis"><em>Master test suite</em></span></a>
        </h5>
<p>
          The master test suite is created with default name <span class="emphasis"><em>Master Test
          Suite</em></span>. There are two methods two reset the name to a different
          value: using the macro <a class="link" href="../../utf_reference/link_references/link_boost_test_module_macro.html" title="BOOST_TEST_MODULE"><code class="computeroutput"><span class="identifier">BOOST_TEST_MODULE</span></code></a> and from within
          the test module initialization function. Former is used for test modules
          that don't have the manually implemented initialization function. Following
          examples illustrate these methods.
        </p>
<h6>
<a name="boost_test.tests_organization.test_tree.master_test_suite.h3"></a>
          <span class="phrase"><a name="boost_test.tests_organization.test_tree.master_test_suite.example_descr0"></a></span><a class="link" href="master_test_suite.html#boost_test.tests_organization.test_tree.master_test_suite.example_descr0">Example:
          Naming master test suite using the macro <code class="computeroutput"><span class="identifier">BOOST_TEST_MODULE</span></code></a>
        </h6>
<div class="informaltable"><table class="table">
<colgroup><col></colgroup>
<thead><tr><th>
                  <p>
                    Code
                  </p>
                </th></tr></thead>
<tbody><tr><td>
<pre xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" class="table-programlisting"><span class="preprocessor">#define</span> <span class="identifier">BOOST_TEST_MODULE</span> <span class="identifier">my</span> <span class="identifier">master</span> <span class="identifier">test</span> <span class="identifier">suite</span> <span class="identifier">name</span>
<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">test</span><span class="special">/</span><span class="identifier">included</span><span class="special">/</span><span class="identifier">unit_test</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>

<span class="identifier">BOOST_AUTO_TEST_CASE</span><span class="special">(</span> <span class="identifier">free_test_function</span> <span class="special">)</span>
<span class="special">{</span>
  <span class="identifier">BOOST_TEST</span><span class="special">(</span> <span class="keyword">true</span> <span class="comment">/* test assertion */</span> <span class="special">);</span>
<span class="special">}</span>
</pre>
                </td></tr></tbody>
</table></div>
<div class="informaltable"><table class="table">
<colgroup><col></colgroup>
<thead><tr><th>
                  <p>
                    Output
                  </p>
                </th></tr></thead>
<tbody><tr><td>
<pre xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" class="table-programlisting"><span class="special">&gt;</span> <span class="identifier">example</span> <span class="special">--</span><span class="identifier">log_level</span><span class="special">=</span><span class="identifier">test_suite</span>
<span class="identifier">Running</span> <span class="number">1</span> <span class="identifier">test</span> <span class="keyword">case</span><span class="special">...</span>
<span class="identifier">Entering</span> <span class="identifier">test</span> <span class="identifier">suite</span> <span class="string">"my master test suite name"</span>
<span class="identifier">Entering</span> <span class="identifier">test</span> <span class="keyword">case</span> <span class="string">"free_test_function"</span>
<span class="identifier">Leaving</span> <span class="identifier">test</span> <span class="keyword">case</span> <span class="string">"free_test_function"</span><span class="special">;</span> <span class="identifier">testing</span> <span class="identifier">time</span><span class="special">:</span> <span class="number">1</span><span class="identifier">ms</span>
<span class="identifier">Leaving</span> <span class="identifier">test</span> <span class="identifier">suite</span> <span class="string">"my master test suite name"</span>

<span class="special">***</span> <span class="identifier">No</span> <span class="identifier">errors</span> <span class="identifier">detected</span>
</pre>
                </td></tr></tbody>
</table></div>
<p>
          If the macro <a class="link" href="../../utf_reference/link_references/link_boost_test_module_macro.html" title="BOOST_TEST_MODULE"><code class="computeroutput"><span class="identifier">BOOST_TEST_MODULE</span></code></a> is defined,
          the test module initialization function is <span class="bold"><strong>automatically
          generated</strong></span> and the macro value becomes the name of the master
          test suite. The name may include spaces.
        </p>
<h6>
<a name="boost_test.tests_organization.test_tree.master_test_suite.h4"></a>
          <span class="phrase"><a name="boost_test.tests_organization.test_tree.master_test_suite.example_descr1"></a></span><a class="link" href="master_test_suite.html#boost_test.tests_organization.test_tree.master_test_suite.example_descr1">Example:
          Naming master test suite explicitly in the test module initialization function</a>
        </h6>
<div class="informaltable"><table class="table">
<colgroup><col></colgroup>
<thead><tr><th>
                  <p>
                    Code
                  </p>
                </th></tr></thead>
<tbody><tr><td>
<pre xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" class="table-programlisting"><span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">test</span><span class="special">/</span><span class="identifier">included</span><span class="special">/</span><span class="identifier">unit_test</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
<span class="keyword">using</span> <span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">unit_test</span><span class="special">;</span>

<span class="identifier">BOOST_AUTO_TEST_CASE</span><span class="special">(</span> <span class="identifier">free_test_function</span> <span class="special">)</span>
<span class="special">{</span>
  <span class="identifier">BOOST_TEST</span><span class="special">(</span> <span class="keyword">true</span> <span class="comment">/* test assertion */</span> <span class="special">);</span>
<span class="special">}</span>

<span class="identifier">test_suite</span><span class="special">*</span> <span class="identifier">init_unit_test_suite</span><span class="special">(</span> <span class="keyword">int</span> <span class="comment">/*argc*/</span><span class="special">,</span> <span class="keyword">char</span><span class="special">*</span> <span class="comment">/*argv*/</span><span class="special">[]</span> <span class="special">)</span>
<span class="special">{</span>
  <span class="identifier">framework</span><span class="special">::</span><span class="identifier">master_test_suite</span><span class="special">().</span><span class="identifier">p_name</span><span class="special">.</span><span class="identifier">value</span> <span class="special">=</span> <span class="string">"my master test suite name"</span><span class="special">;</span>
  <span class="keyword">return</span> <span class="number">0</span><span class="special">;</span>
<span class="special">}</span>
</pre>
                </td></tr></tbody>
</table></div>
<div class="informaltable"><table class="table">
<colgroup><col></colgroup>
<thead><tr><th>
                  <p>
                    Output
                  </p>
                </th></tr></thead>
<tbody><tr><td>
<pre xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" class="table-programlisting"><span class="special">&gt;</span> <span class="identifier">example</span> <span class="special">--</span><span class="identifier">log_level</span><span class="special">=</span><span class="identifier">test_suite</span>
<span class="identifier">Running</span> <span class="number">1</span> <span class="identifier">test</span> <span class="keyword">case</span><span class="special">...</span>
<span class="identifier">Entering</span> <span class="identifier">test</span> <span class="identifier">suite</span> <span class="string">"my master test suite name"</span>
<span class="identifier">Entering</span> <span class="identifier">test</span> <span class="keyword">case</span> <span class="string">"free_test_function"</span>
<span class="identifier">Leaving</span> <span class="identifier">test</span> <span class="keyword">case</span> <span class="string">"free_test_function"</span><span class="special">;</span> <span class="identifier">testing</span> <span class="identifier">time</span><span class="special">:</span> <span class="number">1</span><span class="identifier">ms</span>
<span class="identifier">Leaving</span> <span class="identifier">test</span> <span class="identifier">suite</span> <span class="string">"my master test suite name"</span>

<span class="special">***</span> <span class="identifier">No</span> <span class="identifier">errors</span> <span class="identifier">detected</span>
</pre>
                </td></tr></tbody>
</table></div>
<p>
          Without the <a class="link" href="../../utf_reference/link_references/link_boost_test_main_macro.html" title="BOOST_TEST_MAIN"><code class="computeroutput"><span class="identifier">BOOST_TEST_MAIN</span></code></a> and the <a class="link" href="../../utf_reference/link_references/link_boost_test_module_macro.html" title="BOOST_TEST_MODULE"><code class="computeroutput"><span class="identifier">BOOST_TEST_MODULE</span></code></a> flags defined,
          the test module initialization function has to be manually implemented.
          The master test suite name can be reset at any point within this function.
        </p>
</div>
<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
<td align="left"></td>
<td align="right"><div class="copyright-footer">Copyright © 2001-2020 Boost.Test contributors<p>
        Distributed under the Boost Software License, Version 1.0. (See accompanying
        file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a>)
      </p>
</div></td>
</tr></table>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="test_suite.html"><img src="../../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../test_tree.html"><img src="../../../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../../index.html"><img src="../../../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="test_naming.html"><img src="../../../../../../../doc/src/images/next.png" alt="Next"></a>
</div>
</body>
</html>
